feat: add atomic-key-sewap - #1010

close #957
close #960
close #958
close #961

Description

This PR implements the on-chain Key Rating mechanism for creator keys in creator-keys.

Key holders can submit a score (1–5 stars) for a creator. The contract maintains a running average score for each creator, enforces holder balance requirements, and supports re-ratings without double-counting unique raters.

Key Changes

1. Data Structures & Storage Keys

• Introduced KeyRatingAggregate struct containing:
  • total_score: u64: Sum of all individual scores.
  • count: u32: Number of unique raters.
  • average_score_scaled: u32: Running average scaled by 100 (e.g. 450 represents 4.50 stars).
• Added RatingError enum: NotRegistered, InvalidScore, NotAHolder.
• Added isolated storage keys under FeatureKey:
  • FeatureKey::KeyRatingAggregate(creator)
  • FeatureKey::HolderKeyRating(creator, rater)

2. Contract Entrypoints & Logic

• rate_key(env, creator, rater, score):
  • Requires rater authorization (require_auth()).
  • Validates score range (1..=5).
  • Verifies creator profile existence.
  • Enforces minimum holding balance requirement (holder_balance > 0).
  • Recalculates total_score and count incrementally; updating an existing rating replaces the previous score instead of incrementing count.
  • Emits KeyRatedEvent.
• get_key_rating(env, creator): Read-only view getter for aggregate key ratings.

3. Event Emission

• Added KEY_RATED_EVENT_NAME (symbol_short!("key_rated")).
• Added KeyRatedEvent struct and key_rated_topics helper.

4. Tests

• Added unit tests in test_issues_972_971_968_969.rs covering:
  • Non-holder rating rejection (RatingError::NotAHolder).
  • Invalid score bounds validation (RatingError::InvalidScore).
  • First-time rating calculation.
  • Multi-holder aggregate calculation.
  • Re-rating adjustment without double-counting raters.
  • get_key_rating getter consistency.

Verification

Ran cargo unit tests:

cargo test -p creator-keys --lib test_key_rating_flow_and_rejections